Cadenza : Cadenza Namespace

Overview

Signature

Remarks

Members

Member Details

Maybe<T> Generic Struct

Represents an optional value. An instance of Cadenza.Maybe<T> can contain a value of type T or an indication that the instance contains no value.

public struct Maybe<T> : IEquatable<Maybe<T>>

⊟ Type Parameters

T
The type of the optional value.

⊟ Thread Safety

This type is immutable, and is itself thread safe. However, non-thread safe types may be exposed via Maybe<T>.Value, so even if Cadenza.Maybe<T> is itself thread safe, it may not be safe to fully use it in a thread safe fashion. (Full thread safety depends on the thread safety of T.)

⊟ Remarks

The Cadenza.Maybe<T> value type represents a value of a given type or an indication that the instance contains no value. Such an optional value type is useful in a variety of situations, such as denoting that a conversion couldn't be performed without resorting to an exception or by-ref parameters (out or ref).

An instance of Cadenza.Maybe<T> has two properties, Maybe<T>.HasValue and Maybe<T>.Value. Maybe<T>.HasValue is used to determine whether the current instance currently has a value. It returns true or false, and never throws an exception. Maybe<T>.Value returns the current value of the instance, provided it has one (i.e., Maybe<T>.HasValue is true); otherwise, it throws an exception.

In addition to the above properties, there is a pair of methods, both overloads of Maybe<T>.GetValueOrDefault. The version taking no arguments returns the instance's current value, if it has one; otherwise, it returns the default value of type T. The version taking an argument of type T returns the instance's current value, if it has one; otherwise, it returns the default value argument passed to it.

Cadenza.Maybe<T> instances can be created in one of four ways:

  1. By using the default constructor provided for all value types. This will create an instance that contains no value, and will be equal to Maybe<T>.Nothing.
  2. By explicitly using the Maybe<T>(`0) constructor. This will throw an ArgumentNullException if the value is null.
  3. By using the ObjectCoda.Just``1(``0) extension method. This will throw an ArgumentNullException if the value is null.
  4. By using the ObjectCoda.ToMaybe``1(``0) extension method. If the value is null, then Maybe<T>.Nothing is returned.

Query comprehension support is also provided, allowing:

C# Example 
Assert.AreEqual (Maybe<int>.Nothing,
		from x in 5.ToMaybe ()
		from y in Maybe<int>.Nothing
		select x + y);
Assert.AreEqual (9.ToMaybe (),
		from x in 5.ToMaybe ()
		from y in 4.ToMaybe ()
		select x + y);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Members

See Also: Inherited members from ValueType.

⊟ Public Constructors

Maybe (T)
 Constructs and initializes a new instance of Cadenza.Maybe<T> giving it the specified initial value.

⊟ Public Fields

static readonly
Nothing Maybe<T> . Represents a Cadenza.Maybe<T> containing no value.

⊟ Public Properties

[read-only]
 HasValue bool . Gets a value indicating whether the current Cadenza.Maybe<T> instance has a value.
[read-only]
 Value T . Gets the value of the current Cadenza.Maybe<T> instance.

⊟ Public Methods

Equals (Maybe<T>) : bool
Determines whether the current instance and the specified object represent the same value.
override
Equals (object) : bool
Determines whether the current instance and the specified object represent the same type and value.
override
GetHashCode () : int
Generates a hash code for the current instance.
GetValueOrDefault () : T
Returns the value of the current instance, or if it has none, returns the default value for the type T.
GetValueOrDefault (T) : T
Returns the value of the current instance, or if it has none, returns defaultValue.
Select<TResult> (Func<T, TResult>) : Maybe<TResult>
Projects a Cadenza.Maybe<T> into a Cadenza.Maybe<TResult>.
SelectMany<TCollection,TResult> (Func<T, Maybe<TCollection>>, Func<T, TCollection, TResult>) : Maybe<TResult>
Projects a Cadenza.Maybe<T> and Cadenza.Maybe<TCollection> into a Cadenza.Maybe<TResult>.
override
ToString () : string
Returns a string representation of the value of the current instance.

⊟ Public Operators

static
Equality (Maybe<T>, Maybe<T>) Determines whether the specified Cadenza.Maybe<T> instances are equal.
static
Inequality (Maybe<T>, Maybe<T>) Determines whether the specified Cadenza.Maybe<T> instances are not equal.

⊟ Extension Methods

static
Just<T> (this T) : Maybe<T>
Create a new Cadenza.Maybe<T> instance initialized to a specified value. The returned value will not be Maybe<T>.Nothing.
static
Match<TSource,TResult> (this TSource, params Func<TSource, Maybe<TResult>>[]) : TResult
Converts the TSource instance self into a TResult.
static
ToMaybe<T> (this T) : Maybe<T>
Create a new Cadenza.Maybe<T> instance initialized to a specified value. The returned value may be Maybe<T>.Nothing.
static
TraverseBreadthFirst<TSource,TResult> (this TSource, Func<TSource, TResult>, Func<TSource, IEnumerable<TSource>>) : IEnumerable<TResult>
Traverse a tree in a breadth-first fashion, converting each encountered node.
static
TraverseBreadthFirstWithParent<TSource,TResult> (this TSource, Func<TSource, TResult>, Func<TSource, IEnumerable<TSource>>) : IEnumerable<KeyValuePair<TSource, TResult>>
Traverse a tree in a breadth-first fashion, converting each encountered node.
static
TraverseDepthFirst<TSource,TResult> (this TSource, Func<TSource, TResult>, Func<TSource, IEnumerable<TSource>>) : IEnumerable<TResult>
Traverse a tree in a depth-first fashion, converting each encountered node.
static
TraverseDepthFirstWithParent<TSource,TResult> (this TSource, Func<TSource, TResult>, Func<TSource, IEnumerable<TSource>>) : IEnumerable<KeyValuePair<TSource, TResult>>
Traverse a tree in a depth-first fashion, converting each encountered node.
static
With<TSource,TResult> (this TSource, Func<TSource, TResult>) : TResult
Supports chaining otherwise temporary values.

⊟ Member Details

⊟ Maybe Constructor

Constructs and initializes a new instance of Cadenza.Maybe<T> giving it the specified initial value.

public Maybe (T value)

⊟ Parameters

value
A T which is the value of the new instance.

⊟ Exceptions

Type Reason
ArgumentNullException value is null.

⊟ Remarks

This constructor initializes the Maybe<T>.Value property of the new instance using value.

Note: Once this constructor has executed, calling Maybe<T>.HasValue on the new instance will return true.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Equals Method

Determines whether the current instance and the specified object represent the same value.

public bool Equals (Maybe<T> obj)

⊟ Parameters

obj
An object to compare the current instance against.

⊟ Returns

The following table defines the conditions under which the return value is true or false:

Returned Value HasValue Condition obj.HasValue Condition
true false false
false false true
false true false
Value.Equals(obj.Value) true true

⊟ Remarks

Note: This method implements IEquatable<Maybe<T>>.Equals(`0).

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Equals Method

Determines whether the current instance and the specified object represent the same type and value.

public override bool Equals (object obj)

⊟ Parameters

obj
An object to compare the current instance against.

⊟ Returns

The following table defines the conditions under which the return value is true or false:

Returned Value HasValue Condition obj.HasValue Condition
false The current instance and obj have different types. The current instance and obj have different types.
true false obj is null.
false true obj is null.
true false false
false false true
false true false
Value.Equals(obj.Value) true true

⊟ Remarks

Note: This method overrides object.Equals(object).

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ GetHashCode Method

Generates a hash code for the current instance.

public override int GetHashCode ()

⊟ Returns

If Maybe<T>.HasValue is true, a int containing the hash code for the value of the current instance is returned; otherwise, 0 is returned.

⊟ Remarks

The algorithm used to generate the hash code is unspecified.

Note: This method overrides object.GetHashCode.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ GetValueOrDefault Method

Returns the value of the current instance, or if it has none, returns the default value for the type T.

public T GetValueOrDefault ()

⊟ Returns

A value of type T, which is either the value of the current instance, or if it has none, the default value for the type T (i.e., all-bits-zero).

⊟ Remarks

Note: Maybe<T>.GetValueOrDefault(`0) allows a value other than the default value to be returned if the current instance contains no value.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ GetValueOrDefault Method

Returns the value of the current instance, or if it has none, returns defaultValue.

public T GetValueOrDefault (T defaultValue)

⊟ Parameters

defaultValue
A value of type T to return if the current instance contains no value.

⊟ Returns

A value of type T, which is either the value of the current instance, or if it has none, the value of defaultValue.

⊟ Remarks

Note: Maybe<T>.GetValueOrDefault allows the default value for type T to be returned if the current instance contains no value.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ HasValue Property

Gets a value indicating whether the current Cadenza.Maybe<T> instance has a value.

public bool HasValue { get; }

⊟ See Also

Maybe<T>.Value

⊟ Value

true if the current Cadenza.Maybe<T> instance has a value; otherwise, false.

⊟ Remarks

If the Maybe<T>.HasValue property is true, the value of the current Cadenza.Maybe<T> instance can be accessed via the Maybe<T>.Value property.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Nothing Field

Represents a Cadenza.Maybe<T> containing no value.

public static readonly Maybe<T> Nothing

⊟ Remarks

This value is identical to new Maybe<T>() (i.e. creating an instance using the default constructor).

This member is for "self-documenting" purposes, so that code can explicitly mention that it's returning "nothing".

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ op_Equality Method

Determines whether the specified Cadenza.Maybe<T> instances are equal.

public static bool operator== (Maybe<T> a, Maybe<T> b)

⊟ Parameters

a
The first Cadenza.Maybe<T> to compare.
b
The second Cadenza.Maybe<T> to compare.

⊟ Returns

true if a.Equals(b) returns true; otherwise, false.

⊟ Remarks

Note: See Maybe<T>.Equals(Maybe`1).

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ op_Inequality Method

Determines whether the specified Cadenza.Maybe<T> instances are not equal.

public static bool operator!= (Maybe<T> a, Maybe<T> b)

⊟ Parameters

a
The first Cadenza.Maybe<T> to compare.
b
The second Cadenza.Maybe<T> to compare.

⊟ Returns

true if a.Equals(b) returns false; otherwise, true.

⊟ Remarks

Note: See Maybe<T>.Equals(Maybe`1).

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Select<TResult> Generic Method

Projects a Cadenza.Maybe<T> into a Cadenza.Maybe<TResult>.

public Maybe<TResult> Select<TResult> (Func<T, TResult> selector)

⊟ See Also

ObjectCoda.ToMaybe``1(``0)

⊟ Type Parameters

TResult
The type of the resulting value.

⊟ Parameters

selector
A Func<T, TResult> which is used to convert Maybe<T>.Value into the value returned.

⊟ Returns

A Cadenza.Maybe<TResult> containing Maybe<TResult>.Nothing if Maybe<T>.HasValue is false, or if selector returns null; otherwise returns selector(this).ToMaybe().

⊟ Exceptions

Type Reason
ArgumentNullException selector is null.

⊟ Remarks

This method is provided to support C# query comprehension expressions on Cadenza.Maybe<T> types.

If this contains no value (Maybe<T>.HasValue is false), then Maybe<TResult>.Nothing is returned.

Otherwise, selector(this.Value).ToMaybe() is returned.

C# Example 
Assert.AreEqual (2.Just (),
	1.Just ().Select (x => x + 1));
Assert.AreEqual (2.Just (),
	from x in 1.Just ()
	select x + 1);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ SelectMany<TCollection,TResult> Generic Method

Projects a Cadenza.Maybe<T> and Cadenza.Maybe<TCollection> into a Cadenza.Maybe<TResult>.

public Maybe<TResult> SelectMany<TCollection, TResult> (Func<T, Maybe<TCollection>> selector, Func<T, TCollection, TResult> resultSelector)

⊟ See Also

ObjectCoda.ToMaybe``1(``0)

⊟ Type Parameters

TCollection
The type of the intermediate value within selector.
TResult
The type of the resulting value.

⊟ Parameters

selector
A Func<T, Cadenza.Maybe<TCollection>> used to generate an intermediate value.
resultSelector
A Func<T, TCollection, TResult> which is used to convert Maybe<T>.Value and selector(this).Value into the value returned.

⊟ Returns

A Cadenza.Maybe<TResult> containing Maybe<TResult>.Nothing if either this's or selector(this)'s Maybe<TCollection>.HasValue property is false; otherwise, returns resultSelector(this.Value, selector(this).Value).ToMaybe().

⊟ Exceptions

Type Reason
ArgumentNullException

selector is null.

-or-

resultSelector is null.

⊟ Remarks

This method is provided to support C# query comprehension expressions on Cadenza.Maybe<T> types. SelectMany acts as a "null propagation of nullables" for any type, as opposed to just Nullable<T> types.

If null contains no value (Maybe<TSource>.HasValue is false), then Maybe<TResult>.Nothing is returned.

If selector(this) contains no value (Maybe<TCollection>.HasValue is false), then Maybe<TResult>.Nothing is returned.

Otherwise, resultSelector(this.Value, selector().Value).ToMaybe() is returned. (This means that if resultSelector returns null, then Maybe<TResult>.Nothing is returned.)

C# Example 
Assert.AreEqual (Maybe<int>.Nothing, 
		5.Just().SelectMany(
			x => Maybe<int>.Nothing,
			(x, y) => x + y));
Assert.AreEqual (Maybe<int>.Nothing,
		from x in 5.Just ()
		from y in Maybe<int>.Nothing
		select x + y);
Assert.AreEqual (9.Just (),
		5.Just().SelectMany(
			x => 4.Just (),
			(x, y) => x + y));
Assert.AreEqual (9.Just (),
		from x in 5.Just ()
		from y in 4.Just ()
		select x + y);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ ToString Method

Returns a string representation of the value of the current instance.

public override string ToString ()

⊟ Returns

If Maybe<T>.HasValue is true, Maybe<T>.Value.ToString() is returned; otherwise, string.Empty is returned.

⊟ Remarks

Note: This method overrides object.ToString.

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Value Property

Gets the value of the current Cadenza.Maybe<T> instance.

public T Value { get; }

⊟ See Also

Maybe<T>.HasValue

⊟ Value

If Maybe<T>.HasValue is true, then the value of the current Cadenza.Maybe<T> instance; otherwise, an exception is thrown.

⊟ Exceptions

Type Reason
InvalidOperationException Maybe<T>.HasValue is false, and the current Cadenza.Maybe<T> instance contains no value.

⊟ Remarks

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0